ETO Development Tools 2/ETO Development Tools 2.iso/Tools - Objects/MacApp/MacApp CD Release/MacApp 2.0.1 (Many Libraries)/Interfaces/PInterfaces/UObject.p

Text File | 1990-10-25 | 12.8 KB | 295 lines | [TEXT/MPS ]

{[a-,body+,h-,o=100,r+,rec+,t=4,u+,#+,j=20/57/1$,n-]}
{ UObject.p }
{ Copyright © 1984-1990  Apple Computer, Inc.  All rights reserved. }

{$IFC UNDEFINED UsingIncludes}
{$SETC UsingIncludes := FALSE}
{$ENDC}

{$IFC NOT UsingIncludes}
UNIT UObject;

    INTERFACE
        {$ENDC}

        {$IFC UNDEFINED __UObject__}
        {$SETC __UObject__ := FALSE}
        {$ENDC}

        {$IFC NOT __UObject__}
        {$SETC __UObject__ := TRUE}

        { • Auto-Include the requirements for this unit's interface. }
        {$SETC UObjectIncludes := UsingIncludes}
        {$SETC UsingIncludes := TRUE}
        {$I+}
        {$IFC UNDEFINED __UMacAppUtilities__} {$I UMacAppUtilities.p} {$ENDC}
        {$IFC UNDEFINED UsingMemory} {$I Memory.p} {$ENDC}
        {$SETC UsingIncludes := UObjectIncludes}

        CONST
            kFailNone            = 1;
            kFailAbstract        = 2;
            kFailCoercion        = 3;
            kFailMethNotFound    = 4;

            kInvalidObj         = '*Not an object*';    { return value from LookupObjName if not an
                                                         object}
            kNilClass            = 0;                    { Value for superclass of the root object }

        TYPE

            ObjClassID            = kNilClass..16766;     { Object Class identifier. The first two
                                                         bytes of each object contain the class of
                                                         the object as an ObjClassID. }
            ObjClassIDPtr        = ^ObjClassID;            { Preferred }
            ObjClassIDHandle    = ^ObjClassIDPtr;        { Preferred }
            PObjClassID         = ObjClassIDPtr;        { Left in for compatibility (2.0) }
            HObjClassID         = ObjClassIDHandle;     { Left in for compatibility (2.0) }

{--------------------------------------------------------------------------------------------------}
            { Definition of the system's root object }


            TObject             = OBJECT
                FUNCTION TObject.Clone: TObject;
                { Makes a duplicate copy of SELF. The default calls SELF.ShallowClone, which makes a
                literal copy of instance variables but does not attempt to clone owned objects. A
                subclass which owns other objects should override this to clone the owned objects
                and data structures as well. }

                PROCEDURE TObject.Fields(PROCEDURE DoToField(fieldName: Str255;
                                                             fieldAddr: Ptr;
                                                             fieldType: INTEGER));
                { Calls DoToField once for each instance variable in SELF. fieldName is a string
                representing the name of the variable. fieldAddr is the address of that variable.
                fieldType is one of the types defined in UMacAppUtilities. It is legal to use a
                local variable to hold data and pass the address of that variable to DoToField as
                if it were part of the object's instance variables. By convention, the first call
                to DoToField should have the class name as the fieldName, NIL as the fieldAddr, and
                bClass as the fieldType. Each subclass should override this method, particularly
                with qDebug on, dump its own information, then call INHERITED. }

                PROCEDURE TObject.DynamicFields(PROCEDURE
                                                           DoToField(fieldName: Str255;
                                                                     fieldAddr: Ptr;
                                                                     fieldType: integer));
                { Used by the Inspector and the Debugger to display the contents of this class's
                dynamic area. Defaults to nothing.  Override if your object uses the dynamic area
                See TList for an example. }

                PROCEDURE TObject.ForAllSubClassesDo(PROCEDURE
                                                     DoToSubClass(theClass: ObjClassID));
                { Calls DoToSubClass for each subclass of SELF. The order of traversal is arbitrary;
                see EachSubClass global procedure. }

                PROCEDURE TObject.ForAllSuperClassesDo(PROCEDURE
                                                       DoToSubClass(theClass: ObjClassID));
                { Calls DoToSubClass for each superclass of SELF. The order of traversal is the order
                of ancestry starting from the class of SELF; see EachSuperClass global procedure. }

                PROCEDURE TObject.Free;
                { Called to dispose of an object. Gives object a chance to cleanup after itself.
                Default simply calls SELF.ShallowFree, which makes no attempt to free instance
                variables. Should be overridden by any class which allocates space or owns other
                objects in its instance variables.. Be sure to call INHERITED! }

                FUNCTION TObject.GetClass: ObjClassID;
                { Returns the class ID of SELF. }

                PROCEDURE TObject.GetClassName(VAR clName: MAName);
                { Returns the class name of SELF. }

                FUNCTION TObject.GetClassSize: Size;
                { Returns the basic instantiation size. i.e. the size in bytes of a newly created
                object of this class }

                FUNCTION TObject.GetDynamicPtr: Ptr;
                { Our objects have a dynamic area available. In 2.0 it is at the end of the object
                handle but it may not always be so.  Returns a direct heap pointer to the start
                of the dynamic area.  Use with caution as this pointer can be invalidated if the
                heap compacts. }

                FUNCTION TObject.GetDynamicSize: Size;
                { Our objects can have a dynamic area that can be allocated with a SetDynamicSize
                call.  Returns the size of the dynamic area in bytes. Preferred. }

                FUNCTION TObject.GetInstanceSize: Size;
                { Our objects have a dynamic area after all the fixed fields. Returns the current
                size in bytes of this instance accounting for the dynamic area.
                Left in for compatibility (2.0)  }

                FUNCTION GetSuperClass: ObjClassID;
                { Returns immediate superclass of class. Returns kNilClass for TObject. If we ever
                get MI this will have to be an enumerator. }

                PROCEDURE TObject.GetInspectorName(VAR inspectorName: Str255);
                { Returns additional information useful to the inspector. For instance (ha ha!) a
                TDocument could give its title. }

                PROCEDURE TObject.Initialize;
                { Call this to put a newly created object into a known state. Subclasses should
                override it and call INHERITED. Typically used to put the object into a state where
                it can be safely FREED. Defaults to nothing. }

                PROCEDURE TObject.Inspect;
                { Called from the debugger. Displays the fields of the object in the writeln window
                by calling the object's Fields method, passing InspectField as the DoToField
                routine. You can override this if you want to display any additional information in
                the writeln window when an object is inspected with the MacApp debugger. NOTE: this
                is not currently called from the "Inspector".}

                PROCEDURE TObject.IObject;
                { The ancestral initializer. Should be called in the I<ClassName> chain. i.e. IView
                -> IEvtHandler -> IOBJECT }

                FUNCTION TObject.IsMemberClass(testClass: ObjClassID): BOOLEAN;
                { True if I am a MEMBER of the testClass. i.e. the same class OR a subclass. }

                FUNCTION TObject.IsSameClass(testClass: ObjClassID): BOOLEAN;
                { True if I belong to the immediate class. }

                FUNCTION TObject.Lock(lockIt: BOOLEAN): BOOLEAN;
                { Locks down or unlocks an object AND its dynamic area if any. Returns old state.
                Since objects can float around in memory some occasions may arise where they need
                to be locked down (The Inspect method is an example: since addresses of instance
                variables are being passed, the object had better not move during the Inspect!)
                Typically the old state is saved in a local and re-applied when ascending the
                call chain. Don't forget to re-apply the old state from failure handlers.
                _PLEASE_ use this sparingly and don't just go locking stuff down willy-nilly just
                because you might be afraid of handles. }

                PROCEDURE TObject.SetDynamicSize(newSize: Size);
                { Set this instance's Dynamic Area size in bytes.  The dynamic area starts out
                unallocated. Signals Failure on memory error.  The size applies only to the size
                of the Dynamic Area. Preferred. }

                PROCEDURE TObject.SetInstanceSize(newSize: Size);
                { Set this instance's size in bytes. Thus changing the size of the dynamic area.
                Fails on attempts to set a size smaller than instantiation size and on memory
                error.   Left in for compatibility (2.0) }

                FUNCTION TObject.ShallowClone: TObject;
                { Lowest level method for copying an object; should not be overridden except in very
                unusual cases. Simply calls HandToHand to copy the object data. }

                PROCEDURE TObject.ShallowFree;
                { Lowest level method for freeing an object; should not be overridden except in very
                unusual cases. Simply calls Dispose (the Pascal builtin) to free the object. }

                END;

            TObjectPtr            = ^TObject;             { Preferred }
            TObjectHandle        = ^TObjectPtr;            { Preferred }
            PTObject            = TObjectPtr;            { Left in for compatibility (2.0) }
            HTObject            = TObjectHandle;        { Left in for compatibility (2.0) }

{--------------------------------------------------------------------------------------------------}
            { Utility routines to support objects }

        FUNCTION AddNewObjectsToInspector(add: BOOLEAN): BOOLEAN;
        { Set to true (default) to automatically add all newly created objects to the inspector.
        Function returns old setting. }

        FUNCTION AllocateObjectsFromPerm(allocateFromPerm: BOOLEAN): BOOLEAN;
        { Set to TRUE to make object allocation calls use Permanent memory (the default).
        Set to false to make object allocation calls use temporary memory (if they cannot be
        allowed to fail).  Returns old state }

        FUNCTION DisciplineMethodCalls(discipline: BOOLEAN): BOOLEAN;
        { Set to true to discipline all method calls that go through the dispatcher. Function returns
        old setting. }

        PROCEDURE EachClassDo(PROCEDURE DoToClass(theClass: ObjClassID));
        { Calls DoToClass for each class in the application }

        PROCEDURE EachSubClassDo(testClass: ObjClassID;
                                 PROCEDURE DoToClass(theClass: ObjClassID));
        { Calls DoToClass for subclass of the test class. Uses EachClassDo, so the order of iteration
        is not based on the class hierarchy but on the sequence of class IDs in the class table,
        Sorry… }

        PROCEDURE EachSuperClassDo(testClass: ObjClassID;
                                   PROCEDURE DoToClass(theClass: ObjClassID));
        { Calls DoToClass for superclass of the test class. Order of iteration is in order of
        ancestry. }

        PROCEDURE FailNonObject(obj: UNIV TObject);
        { called by dispatcher to discipline an object. Invokes failure if parameter is not IsObject
        }

        PROCEDURE FreeIfObject(obj: TObject);
        { IF obj <> NIL THEN obj.Free; useful for freeing an object that might sometimes be NIL. }

        PROCEDURE FreeObject(obj: TObject);
        { Synonym for FreeIfObject. Left in for compatibility (2.0) }

        FUNCTION GetClassSizeFromID(classID: ObjClassID): Size;
        { Given an object id, return the class's instantiation size. }

        PROCEDURE GetClassNameFromID(classID: ObjClassID;
                                     VAR clName: MAName);
        { Given an object id, return the object's name. ??? add error checking ??? }

        FUNCTION GetClassIDFromName(clName: MAName): ObjClassID;
        { Given an object name, return its id. }

        FUNCTION GetClassID(obj: TObject): ObjClassID;
        { Given an object, return the object's ClassID. }

        FUNCTION GetSuperClassID(objID: ObjClassID): ObjClassID;
        { returns immediate superclass of class. Returns kNilClass for TObject. If we ever get MI
        this will have to be an enumerator. }

        PROCEDURE IDUobject;
        { Writeln UObject compile date }

        PROCEDURE InitUObject;
        { Essential one time initialization for this unit }

        PROCEDURE InspectObject(obj: TObject);
        { Called by debugger to inspect an object. NOTE: not currently called by the "inspector" }

        FUNCTION IsObject(obj: UNIV TObject): BOOLEAN;
        { Debugging check. Returns true if obj references a real object, false if obj is NIL or a
        non-object reference. This is not an absloutely sure-fire test of objectness, but does
        validate the following: (1) is it a handle? (2) is the handle non-purgeable? (3) is the
        class ID valid? (4) is the handle size at least as large as the class size? }

        FUNCTION IsClassIDMemberClass(testClass: ObjClassID;
                                      superClass: ObjClassID): BOOLEAN;
        { tests the testClass for MEMBERship in the superclass }

        FUNCTION IsMemberClassID(obj: TObject;
                                 objID: ObjClassID): BOOLEAN;
       { Returns true if obj references the class or a subclass of the class represented by objID. }

        PROCEDURE OBJFail(error: INTEGER);
        { Entered due (presumably) to some object failing a test for objectness. There are two codes
        which result in a special message: kFailCoercion, which means that an object could not be
        coerced to a class due to not being a subclass of that class; and kFailMethNotFound, which
        means a method was called for a class, but that method is not defined for the class. Other
        codes are allowed but are not given special treatment. In qDebug mode a ProgramBreak
        preceeds the Failure. }

        FUNCTION NewObjectByClassId(classID: ObjClassID): TObject;
        { Creates an object of the given class id }

        FUNCTION NewObjectByClassName(className: MAName): TObject;
        { Creates an object of the given class name }

        FUNCTION VerboseIsObject(obj: UNIV TObject): BOOLEAN;
        { Debugging check. Indicate whether the parameter appears to really be an object and emit
        diagnostics if it is not }

        PROCEDURE WrLblField(fieldName: Str255;
                             fieldAddr: Ptr;
                             fieldType: INTEGER);
        { Writes the given field in the writeln window in the form: WRITE(fieldName, '=',
        valueAsString).}
        {$ENDC}

        {$IFC NOT UsingIncludes}
END.
{$ENDC}